<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libcoap: coap_session(3)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">libcoap<span id="projectnumber">&#160;4.2.0</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('man_coap_session.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">coap_session(3)</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>coap_session</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /></head><body><div xml:lang="en" class="refentry" lang="en"><a id="id1337"></a><div class="titlepage"></div><div class="refnamediv"><h2>NAME</h2><p>coap_session, coap_new_client_session, coap_new_client_session_psk, coap_new_client_session_pki, coap_session_reference, coap_session_release, coap_session_set_mtu, coap_session_max_pdu_size, coap_session_str — Work with CoAP sessions</p></div><div class="refsynopsisdiv"><a id="_synopsis"></a><h2>SYNOPSIS</h2><p><span class="strong"><strong>#include &lt;coap2/coap.h&gt;</strong></span></p><p><span class="strong"><strong>coap_session_t *coap_new_client_session(coap_context_t *<span class="emphasis"><em>context</em></span>,
const coap_address_t *<span class="emphasis"><em>local_if</em></span>, const coap_address_t *<span class="emphasis"><em>server</em></span>,
coap_proto_t <span class="emphasis"><em>proto</em></span>);</strong></span></p><p><span class="strong"><strong>coap_session_t *coap_new_client_session_psk(coap_context_t *<span class="emphasis"><em>context</em></span>,
const coap_address_t *<span class="emphasis"><em>local_if</em></span>, const coap_address_t *<span class="emphasis"><em>server</em></span>, coap_proto_t
<span class="emphasis"><em>proto</em></span>, const char *<span class="emphasis"><em>identity</em></span>, const uint8_t *<span class="emphasis"><em>key</em></span>, unsigned <span class="emphasis"><em>key_len</em></span>);</strong></span></p><p><span class="strong"><strong>coap_session_t *coap_new_client_session_pki(coap_context_t *<span class="emphasis"><em>context</em></span>,
const coap_address_t *<span class="emphasis"><em>local_if</em></span>, const coap_address_t *<span class="emphasis"><em>server</em></span>, coap_proto_t
<span class="emphasis"><em>proto</em></span>, coap_dtls_pki_t *<span class="emphasis"><em>setup_data</em></span>);</strong></span></p><p><span class="strong"><strong>coap_session_t *coap_session_reference(coap_session_t *<span class="emphasis"><em>session</em></span>);</strong></span></p><p><span class="strong"><strong>void coap_session_release(coap_session_t *<span class="emphasis"><em>session</em></span>);</strong></span></p><p><span class="strong"><strong>void coap_session_set_mtu(coap_session_t *<span class="emphasis"><em>session</em></span>, unsigned <span class="emphasis"><em>mtu</em></span>);</strong></span></p><p><span class="strong"><strong>size_t coap_session_max_pdu_size(coap_session_t *<span class="emphasis"><em>session</em></span>);</strong></span></p><p><span class="strong"><strong>void coap_session_set_app_data(coap_session_t *<span class="emphasis"><em>session</em></span>, void *<span class="emphasis"><em>data</em></span>);</strong></span></p><p><span class="strong"><strong>void *coap_session_get_app_data(const coap_session_t *<span class="emphasis"><em>session</em></span>);</strong></span></p><p><span class="strong"><strong>const char *coap_session_str(const coap_session_t *<span class="emphasis"><em>session</em></span>);</strong></span></p><p>Link with <span class="strong"><strong>-lcoap-2</strong></span>, <span class="strong"><strong>-lcoap-2-gnutls</strong></span>,
<span class="strong"><strong>-lcoap-2-openssl</strong></span> or
<span class="strong"><strong>-lcoap-2-tinydtls</strong></span> depending on your (D)TLS library
type.</p></div><div class="refsect1"><a id="_description"></a><h2>DESCRIPTION</h2><p>This man page focuses on the CoAP Session.</p><p>The CoAP stack’s global state is stored in a coap_context_t Context object.
Resources, Endpoints and Sessions are associated with this context object.
There can be more than one coap_context_t object per application, it is up to
the application to manage each one accordingly.</p><p>A CoAP Session maintains the state of an ongoing connection between a Client
and Server which is stored in a coap_session_t Session object.</p><p>The Session network traffic can be encrypted or un-encrypted if there is an
underlying TLS library.</p><p>If TLS is going to be used for encrypting the network traffic, then the TLS
information for Pre-Shared Keys (PSK) or Public Key Infrastructure (PKI) needs
to be configured before any network traffic starts to flow. For Servers, this
has to be done before the Endpoint is created, for Clients, this is done
during the Client Session set up.</p><p>For Servers, all the encryption information is held internally by the TLS
Context level and the CoAP Context level as the Server is listening for new
incoming traffic based on the Endpoint definition.  The TLS and CoAP session
will not get built until the new traffic starts, which is done by the libcoap
library, with the session having a reference count of 1.</p><p>For Clients, all the encryption information can be held at the TLS Context and
CoAP Context levels, or at the TLS Session and CoAP Session levels.  If
defined at the Context level, then when Sessions are created, they will
inherit the Context definitions, unless they have separately been defined for
the Session level, in which case the Session version will get used.
Typically the information will be configured at the Session level for Clients.</p><p>In principle the set-up sequence for CoAP Servers looks like
(see coap_context(3) for further information on the functions)</p><pre class="screen">coap_new_context()
coap_context_set_pki_root_cas() - if the root CAs need to be updated and PKI
coap_context_set_pki() and/or coap_context_set_psk() - if encryption is required
coap_new_endpoint()</pre><p>Multiple endpoints can be set up per Context, each listening for a new traffic
flow with different TCP/UDP protocols, TLS protocols, port numbers etc. When a
new traffic flow is started, then the CoAP library will create and start a new
server session.</p><p>In principle the set-up sequence for CoAP Clients looks like</p><pre class="screen">coap_new_context()
coap_context_set_pki_root_cas() if the root CAs need to be updated and PKI
coap_new_client_session(), coap_new_client_session_pki() or coap_new_client_session_psk()</pre><p>Multiple client sessions are supported per Context.</p><p>Different CoAP protocols can be defined for <span class="emphasis"><em>proto</em></span> - the current supported
list is:</p><pre class="programlisting">COAP_PROTO_UDP
COAP_PROTO_DTLS
COAP_PROTO_TCP
COAP_PROTO_TLS</pre><p>The <span class="strong"><strong>coap_new_client_session</strong></span>() function initiates a new client session
associated with <span class="emphasis"><em>context</em></span> to the specified <span class="emphasis"><em>server</em></span> using the CoAP protocol
<span class="emphasis"><em>proto</em></span>.  If the port is not specified in <span class="emphasis"><em>server</em></span>, then the default CoAP
port is used.  Normally <span class="emphasis"><em>local_if</em></span> would be set to NULL, but by specifying
<span class="emphasis"><em>local_if</em></span> the source of the network session can be bound to a specific IP
address or port.  The session will initially have a reference count of 1.</p><p>The <span class="strong"><strong>coap_new_client_session_pki</strong></span>() function, for a specific <span class="emphasis"><em>context</em></span>, is
used to configure the TLS context using the <span class="emphasis"><em>setup_data</em></span> variables as defined
in the coap_dtls_pki_t structure - see <span class="strong"><strong>coap_encrytion</strong></span>(3).
The session will initially have a reference count of 1.</p><p>The <span class="strong"><strong>coap_new_client_session_psk</strong></span>() function, for a specific <span class="emphasis"><em>context</em></span>, is
used to configure the TLS context using the client <span class="emphasis"><em>identity</em></span>, Pre-Shared Key
<span class="emphasis"><em>key</em></span> with length <span class="emphasis"><em>key_len</em></span>.  All 3 parameters must be defined, NULL is not
valid.  An empty string is not valid for <span class="emphasis"><em>identity</em></span>.  <span class="emphasis"><em>key_len</em></span> must be greater
than 0.  This function also includes the <span class="emphasis"><em>server</em></span> to connect to,
optionally the local interface <span class="emphasis"><em>local_if</em></span> to bind to and the CoAP protocol
<span class="emphasis"><em>proto</em></span> to use.  The session will initially have a reference count of 1.</p><p>The <span class="strong"><strong>coap_session_reference</strong></span>() is used to increment the reference count of
the <span class="emphasis"><em>session</em></span>.  Incrementing the reference count by an application means that
the library will not inadvertently remove the session when it has finished
processing the session.</p><p>The <span class="strong"><strong>coap_session_release</strong></span>() function must be used to decrement the <span class="emphasis"><em>session</em></span>
reference count, which when it gets to 0, will free off the session if this is
a Client, which then clears all entries from the receive queue and send
queue.  If the reference count goes to 0 for a Server, then the <span class="emphasis"><em>session</em></span> is
added to a free pool ready for subsequent re-use. If the Server <span class="emphasis"><em>session</em></span> is
not used for 5 minutes, then it will get completely freed off.</p><p>The <span class="strong"><strong>coap_sesson_set_default_mtu</strong></span>() function is used to set the MTU size
(the maximum message size) of the data in a packet, excluding any IP or
TCP/UDP overhead to <span class="emphasis"><em>mtu</em></span> for the <span class="emphasis"><em>session</em></span>.</p><p>The <span class="strong"><strong>coap_session_max_pdu_size</strong></span>() funcition is used to get the maximum MTU
size of the data for the <span class="emphasis"><em>session</em></span>.</p><p>The <span class="strong"><strong>coap_session_set_app_data</strong></span>() funstion is used to define a <span class="emphasis"><em>data</em></span> pointer
for the <span class="emphasis"><em>session</em></span> which can then be retieved at a later date.</p><p>The <span class="strong"><strong>coap_session_get_app_data</strong></span>() function is used to retrieve the data
pointer previously defined by <span class="strong"><strong>coap_session_set_app_data</strong></span>().</p><p>The <span class="strong"><strong>coap_session_str</strong></span>() function is used to get a string containing the
information about the <span class="emphasis"><em>session</em></span>.</p></div><div class="refsect1"><a id="_return_values"></a><h2>RETURN VALUES</h2><p><span class="strong"><strong>coap_new_client_session</strong></span>(), <span class="strong"><strong>coap_new_client_session_psk</strong></span>(),
<span class="strong"><strong>coap_new_client_session_pki</strong></span>() functions returns a newly created client
session or NULL if there is a creation failure.</p><p><span class="strong"><strong>coap_session_reference</strong></span>() function returns a pointer to the session.</p><p><span class="strong"><strong>coap_session_get_app_data</strong></span>() function return a previously defined pointer.</p><p><span class="strong"><strong>coap_session_max_pdu_size</strong></span>() function returns the MTU size.</p><p><span class="strong"><strong>coap_session_str</strong></span>() function returns a description string of the
session.</p></div><div class="refsect1"><a id="_examples"></a><h2>EXAMPLES</h2><p><span class="strong"><strong>CoAP Client Non-Encrypted Setup</strong></span></p><pre class="programlisting">#include &lt;coap2/coap.h&gt;

#include &lt;netinet/in.h&gt;

static coap_session_t *
setup_client_session (struct in_addr ip_address) {
  coap_session_t *session;
  coap_address_t server;
  /* See coap_context(3) */
  coap_context_t *context = coap_new_context(NULL);

  if (!context)
    return NULL;

  coap_address_init(&amp;server);
  server.addr.sa.sa_family = AF_INET;
  server.addr.sin.sin_addr = ip_address;
  server.addr.sin.sin_port = htons (5683);

  session = coap_new_client_session(context, NULL, &amp;server, COAP_PROTO_UDP);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session-&gt;context */
  return session;
}</pre><p><span class="strong"><strong>CoAP Client PKI Setup</strong></span></p><pre class="programlisting">#include &lt;coap2/coap.h&gt;

#include &lt;netinet/in.h&gt;

static int
verify_cn_callback(const char *cn,
                   const uint8_t *asn1_public_cert,
                   size_t asn1_length,
                   coap_session_t *session,
                   unsigned depth,
                   int validated,
                   void *arg
) {
  /* Check that the CN is valid */

  /* ... */

  return 1;
}

static coap_session_t *
setup_client_session_pki (struct in_addr ip_address,
                          const char *public_cert_file,
                          const char *private_key_file,
                          const char *ca_file
) {
  coap_session_t *session;
  coap_address_t server;
  coap_dtls_pki_t dtls_pki;
  /* See coap_context(3) */
  coap_context_t *context = coap_new_context(NULL);

  if (!context)
    return NULL;

  coap_address_init(&amp;server);
  server.addr.sa.sa_family = AF_INET;
  server.addr.sin.sin_addr = ip_address;
  server.addr.sin.sin_port = htons (5684);

  memset (&amp;dtls_pki, 0, sizeof (dtls_pki));

  /* See coap_encryption(3) */
  dtls_pki.version                 = COAP_DTLS_PKI_SETUP_VERSION;
  dtls_pki.verify_peer_cert        = 1;
  dtls_pki.require_peer_cert       = 1;
  dtls_pki.allow_self_signed       = 1;
  dtls_pki.allow_expired_certs     = 1;
  dtls_pki.cert_chain_validation   = 1;
  dtls_pki.cert_chain_verify_depth = 1;
  dtls_pki.check_cert_revocation   = 1;
  dtls_pki.allow_no_crl            = 1;
  dtls_pki.allow_expired_crl       = 1;
  dtls_pki.validate_cn_call_back   = verify_cn_callback;
  dtls_pki.cn_call_back_arg        = NULL;
  dtls_pki.validate_sni_call_back  = NULL;
  dtls_pki.sni_call_back_arg       = NULL;
  dtls_pki.additional_tls_setup_call_back = NULL;
  dtls_pki.sni                     = NULL;
  dtls_pki.pki_key.key_type        = COAP_PKI_KEY_PEM;
  dtls_pki.pki_key.key.pem.ca_file = ca_file;
  dtls_pki.pki_key.key.pem.public_cert = public_cert_file;
  dtls_pki.pki_key.key.pem.private_key = private_key_file;

  session = coap_new_client_session_pki(context, NULL, &amp;server,
                                        COAP_PROTO_DTLS, &amp;dtls_pki);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session-&gt;context */
  return session;
}</pre><p><span class="strong"><strong>CoAP Client PSK Setup</strong></span></p><pre class="programlisting">#include &lt;coap2/coap.h&gt;

#include &lt;netinet/in.h&gt;

static coap_session_t *
setup_client_session_psk (struct in_addr ip_address,
                          const char *identity,
                          const uint8_t *key,
                          unsigned key_len
) {
  coap_session_t *session;
  coap_address_t server;
  /* See coap_context(3) */
  coap_context_t *context = coap_new_context(NULL);

  if (!context)
    return NULL;

  coap_address_init(&amp;server);
  server.addr.sa.sa_family = AF_INET;
  server.addr.sin.sin_addr = ip_address;
  server.addr.sin.sin_port = htons (5684);

  session = coap_new_client_session_psk(context, NULL, &amp;server,
                                        COAP_PROTO_DTLS, identity, key, key_len);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session-&gt;context */
  return session;
}</pre><p><span class="strong"><strong>CoAP Client Setup</strong></span></p><pre class="programlisting">#include &lt;coap2/coap.h&gt;

#include &lt;netinet/in.h&gt;

static coap_session_t *
setup_client_session (struct in_addr ip_address) {
  coap_session_t *session;
  coap_address_t server;
  /* See coap_context(3) */
  coap_context_t *context = coap_new_context(NULL);

  if (!context)
    return NULL;

  coap_address_init(&amp;server);
  server.addr.sa.sa_family = AF_INET;
  server.addr.sin.sin_addr = ip_address;
  server.addr.sin.sin_port = htons (5683);

  session = coap_new_client_session(context, NULL, &amp;server,
                                        COAP_PROTO_DTLS);
  if (!session) {
    coap_free_context(context);
    return NULL;
  }
  /* The context is in session-&gt;context */
  return session;
}</pre></div><div class="refsect1"><a id="_see_also"></a><h2>SEE ALSO</h2><p><a href="man_coap_context.html" target="_self"><span class="strong"><strong>coap_context</strong></span>(3)</a>, <a href="man_coap_resource.html" target="_self"><span class="strong"><strong>coap_resource</strong></span>(3)</a>, <a href="man_coap_encryption.html" target="_self"><span class="strong"><strong>coap_encryption</strong></span>(3)</a> and <a href="man_coap_tls_library.html" target="_self"><span class="strong"><strong>coap_tls_library</strong></span>(3)</a></p></div><div class="refsect1"><a id="_further_information"></a><h2>FURTHER INFORMATION</h2><p>See "RFC7252: The Constrained Application Protocol (CoAP)" for further
information.</p></div><div class="refsect1"><a id="_bugs"></a><h2>BUGS</h2><p>Please report bugs on the mailing list for libcoap:
<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a></p></div><div class="refsect1"><a id="_authors"></a><h2>AUTHORS</h2><p>The libcoap project &lt;<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a>&gt;</p></div></div></body></html> coap_session(3)</p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Fri Dec 27 2024 09:57:44 for libcoap by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8 </li>
  </ul>
</div>
</body>
</html>
